Tech Arsenal 1

home *** CD-ROM | disk | FTP | other *** search

/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-04 / serial.zip / SERIAL.DOC < prev next >

Wrap

Text File | 1993-01-04 | 31.0 KB | 991 lines

========================== = SERIAL = = Vers. 1.00 = = - by - = = Steven E. Margison = ========================== Program and Documentation Copyright 1986 by Steven E. Margison -- All Rights Reserved SERIAL Manual Page 1 SERIAL -- Serial Number Installer I. INTRODUCTION You write commercial software. You want to track which copies of your program go to which purchaser. Or, you write shareware software. Somebody registers a copy with you. Wouldn't it be nice to know where that copy came from in the first place? Well, solve both problems with SERIAL. This unique program allows the easy insertion of serial numbers into any type of file, whether text or executable. And, it remembers the last number and how to patch your files as well. II. SYSTEM REQUIREMENTS * Dual floppy drives or hard drive plus floppy. * CGA, Mono, or EGA card. If Mono card not in use, SERIAL forces video mode 2 (Black/White 80 column). * 32K of available memory for program. * No color is used -- any monitor except 40 column types are allowable. SERIAL Manual Page 2 III. STRATEGY OF OPERATION and TERMINOLOGY The process of installing a serial number into a program is actually quite simple. The program (or text file) is created with a "dummy" serial number string. Then, SERIAL is told to search the file for that string and replace it with another string. A direct byte-for-byte substitution. You could do the same thing with Norton Utilities (r) but it would drive you crazy after about five files. SERIAL does the process in a friendly, menu-driven operation, with error checks, automatic number increment, and data logging. In order to understand the remainder of this manual better, these terms will be used: "TARGET FILE" -- This is the file which will be patched. "LOG FILE" -- The file which will contain location information and last number used. There may be any number of these if desired. "SERIAL TEMPLATE" -- The string which will be placed into the target file. This string has a designated area for the serial number. "SEARCH TEMPLATE" -- The dummy string in the target which will be replaced. "SERIAL NUMBER" -- a decimal number from 0000 - 9999 which is merged into the serial template. "TILDE" -- the '~' character, which is used in the serial template to indicate the position of the serial number. SERIAL Manual Page 3 IV. OPERATION SERIAL requires no command line options. Simply execute the program from any directory. Of course, DOS must be able to locate SERIAL.COM, so make sure that it is in your current directory or in a directory specified by your PATH environment variable. The main menu will appear on the screen and a prompt line will appear at the bottom: +----------------------------------------------------------------------+ | PROGRAM SERIALIZER V1.00 Serial #000.0000.0000 | | - by Steven E. Margison - | | Copyright 1986 -- All Rights Reserved | | | | F1 File to Serialize: | | F2 Logging File: | | F3 Serial # Template: | | F4 Search Template: | | F5 -- Search for Location -- | | F6 -- Modify the File -- | | F7 Auto-Increment is OFF | | F8 Next Serial Number: | | F9 -- Update Log File -- | | F10 HELP | | ESC -- Return to DOS -- | | | | | | waiting..._ | +----------------------------------------------------------------------+ Briefly, the function keys are: F1 File to Serialize This key is used to specify the target filename. Be sure to include any drive and path required. Maximum length is 32 characters total. A "beep" will sound for any illegal character, or when the 32 character limit is reached. Press <escape> at any time to abort the operation and return to the program prompt. Press <enter> to complete the filename and return to the prompt. The backspace key may be used to edit the filename before pressing <enter>. F2 Logging File This key selects the file to use for logging information. It operates the same as F1. After entering a filename, you will be asked if you wish the filename to be installed as the default. A response of 'Y' or 'y' will install the filename as a default, providing SERIAL.COM is still available. Any other response simply selects the file for current usage. To uninstall a default file, press F2, then <enter>. Then, press 'Y' to the question. A null filename causes any presently installed filename to be uninstalled. SERIAL Manual Page 4 F3 Serial # Template This key is used to specify the serial template. Up to 16 characters may be specified. There must be at least one tilde character. All printable characters are allowed. Backspace, <enter>, and <escape> work as for F1 and F2. F4 Search Template This key allows selection of the search template. It functions as for key F3, although the tilde characters are not required. This string must be specified exactly as it appears in an unmodified target file. F5 Search for Location After selection of a target file and search template, this key is used to commence a search of the target file for the specified search template. When found, location information is saved within the program for use when installing the serial number string. F6 Modify the File This operation places the final serial number string into the target file. It requires prior entry of the target filename, search template, serial template, and serial number. If a search operation on the file has already been accomplished the installation will be performed. Otherwise, an error message will be displayed and it will be necessary to do a search (F5) operation first. F7 Auto-Increment This key toggles the auto-increment function OFF and ON, with the line always indicating the current state. If auto-increment is ON, then the serial number will be incremented after each modification operation. Otherwise, the number will not be changed. F8 Next Serial Number: This line shows the current serial number. Use of this key allows changing the number. As with other keys, backspace, <enter>, and <escape> are active. However, this function allows only numerical entry of four digits. If less than four digits are entered an error message is issued. Use leading zeros if needed. F9 Update Log File This key is active only if a logging file has been selected. When used, the selected logging file is updated with current data. The current serial number is always saved in the first line of the logging file. The target filename is entered into the logging file along with the selected search template and location of the search template in the target. If the target already exists in the logging file, its information is updated. SERIAL Manual Page 5 This allows for updating a file's location information in the event the target file is modified, changing the location of the search template. F10 HELP This key opens up a second menu which allows selection of help on each of the function keys. Pressing <escape> returns you to the main menu. ESC -- Return to DOS -- Use this key to quit SERIAL. SERIAL Manual Page 6 V. TEMPLATE CONSIDERATIONS A dummy serial number template must be placed in the original target file. The template may be up to 16 characters in length and contain any printable characters. This template will be replaced in the target file by the serial number string, which consists of the merging of the serial number and the serial template. The serial template contains one or more tilde characters, which indicate the location of the serial number. For example, a portion of the menu may look thus: F3 Serial # Template: A~~~~B F4 Search Template: A0000B F8 Next Serial Number: 1165 In this case, the target file will be searched for the string A0000B when the F5 key is pressed. When the F6 key is pressed, the serial number 1165 is merged into the serial template at the tilde characters yielding a serial number string of A1165B. If fewer than 4 tilde characters are present in the serial template, only the appropriate number of digits from the serial number will be merged, least significant justified. If more than 4 tilde characters are specified, the left-most four will be merged and the remainder will be unchanged. If there are two separate fields of tilde characters, such as "A~~~B~~~C" only the leftmost will be recognized. Note that the length of the serial template must be exactly the same length as the search template, since it is not possible to patch a file with a different number of bytes. Consider the following C language line in the traditional file "foobar.com": puts("Serial Number: A0000"); To patch this file with serial number A1234 follow these steps: Press F2 and type TEMP.LOG<enter> Press F1 and type FOOBAR.COM<enter> Press F4 and type A0000<enter> Press F3 and type A~~~~<enter> Press F8 and type 1234<enter> Press F5 Press F7 Press F6 Press F9 This will install the number in the target file and update the logging file. Upon completion the logging file "TEMP.LOG" would look like this: 1235 foobar.com 0 0 0 0 0 A0000B The several fields of zeros would actually be information relating to the position of the search template in the file. The serial number can be as simple as the above example, or as complex as desired. Take the following example: puts("Serial Number: MMDDYY-xxx-VVV"); The search string is MMDDYY-xxx-VVV. When creating a distribution diskette of the program, the MMDDYY might become the date the disk was created, the xxx would be the serial SERIAL Manual Page 7 number (note the use of only 3 digits this time), and the VVV might be the version number. Releasing serial number 702 on 9-23-86, version 2.37 would require a serial template entry of: 092386-~~~-237 and a serial number entry of 702. In the above examples the tilde character has not been used in the search template nor in the dummy program strings. There is no reason that this couldn't be done, however. (In fact, I program my own code in that manner.) After SERIAL has the location of the search template, either by searching or reading the location from the logging file, installation of the serial number string is performed without re-checking for the search template. This allows changing the serial number string of a program which has already been serialized, and which no longer has the dummy search string. However, this also makes it very important to repeat the search on the target file any time the target is modified in such a way as to potentially change the location of the search template. SERIAL Manual Page 8 VI. THE LOG FILE The log file is used to expedite operation of SERIAL. Although several logging files may be used if desired, it is probably more common to use a single file and cause it to be installed as the default file. When SERIAL is invoked with an installed logging file, the file is immediately read and the serial number is retrieved from the file. This eliminates the need to manually keep track of the last number issued. Whenever a target filename is selected, the logging file is searched to see if that filename is already in the file. If so, its search template is displayed on the F4 menu line, and the location information is read from the file. It is then unnecessary to perform a search operation. Of course, if the generic target file has been modified the search template location may have changed, so it will be necessary to do another search to update the new location. If a new target file is selected while a logging file is in effect, the logging file will again be searched for appropriate information. If the logging file is changed while a target file is selected, the new log file will be read for its serial number, and scanned for an entry pertaining to the currently selected target file. Note that target filenames are entered in the log file exactly as they are entered on the menu. Therefore, "B:FOOBAR.COM" and "A:FOOBAR.COM" will have separate entries, even though they may be the same file. Be sure to do an update operation on the log file whenever information has changed, such as a new target file, new location search, or changed serial number. SERIAL will warn you if you are about to do an operation which will lose information which should go into the log file. SERIAL Manual Page 9 VII. ERROR MESSAGES All error messages are displayed on the main menu in place of the prompt line. Strike any key to clear the error. "No logging file has been selected. <F2>" An attempt was made to update the log file with F9, except that there is no specified log file. Use F2 to enter a log file name. "No target file has been selected. <F1>" An attempt was made to search or modify a target with F5 or F6, except no target file has been selected with F1. "No template specified. <F3>" An attempt was made to modify a file without first selecting the serial template. Use F3 to select a template. "No search template specified. <F4>" An attempt was made to search a target file without first selecting the search template with F4. "Template position not located. <F5>" SERIAL has no knowledge of the location of the search template in the target file. Either read in the data from a logging file or perform a search operation with F5. "No serial number entered. <F8>" A modify operation was attempted without first specifying a starting serial number with F8. "Failure opening logging file." The specified log file could not be properly opened. "Failure to open temporary logging file." SERIAL uses a temporary logging file for updating the specified logging file. This error occurs when the temporary file SERIAL.TMP cannot be opened. If this error occurs, the logging file will not be updated. "Failure to open target file." The specified target could not be opened for search or modification. "Read failure on target file." During a search or modify operation on the target file a fatal error occurred. SERIAL Manual Page 10 "No serial number field in template. Redefine template." The serial template specified with F3 contains no tilde characters for merging the serial number. "Serial number must be 4 digits long." The serial number selected with F8 had fewer than four digits. Use leading zeros if necessary to pad number to four digits. "<F3> and <F4> templates not the same length." The search and serial templates must be the same length since it is not possible to alter the length of the target file. "Seek error on target file update." During modification of the target file, a fatal error occurred. "WARNING! Error on writing target file. Target file may be corrupted." A write error occurred during the modification of the target file. Integrity of the target file is in question. "Cannot locate SERIAL.COM to install defaults." SERIAL.COM could not be located to install the default logging file. This could be caused by switching disks after SERIAL was invoked, invoking SERIAL with a directory or drive path which is not in the PATH, or by renaming SERIAL.COM to something else. "Error on installation of defaults." An error occurred during installation of the default logging filename. Safety dictates replacing the current SERIAL.COM with a backup copy. "Altered logging information not save to disk." This warning indicates that either the serial number has been altered or new location information has been collected, but an update of the logging file has not been done to save the changes. After clearing this error, the user is prompted to lose information or not. SERIAL Manual Page 11 VIII. ONLINE HELP Pressing the F10 key will change from the main menu to the help menu: +-------------------------------------------------------+ | Select function key for which help is needed | | or ESCape to return to main menu. | | F1 - Target Files | | F2 - Logging Files | | F3 - Serial Number Template | | F4 - Search Template | | F5 - Location Search | | F6 - Serial Number Installation | | F7 - Autoincrement | | F8 - Serial Number Selection | | F9 - Update Logging File | | ==> | +-------------------------------------------------------+ Selecting one of the function keys will give a brief description of that function, and report any current selections for that function. Pressing the <escape> key returns to the main menu. SERIAL Manual Page 12 IX. SHAREWARE By now, the shareware concept should be familiar to PC users. In a nutshell, shareware is "try-before-you-buy" software, reasonably priced and user-supported. This simply means that you can get shareware software for free from anyone who has a copy, or often from bulletin board systems. If you use and like the program, then the author requests a donation to support further software development. By registering and making a donation, you will often also receive notice of available upgrades or supplemental programs. Of course, payment under shareware is voluntary, but if the program is useful and the price is right, why not pay the dues and provide the incentive and reward necessary to continue development of new and better software? SERIAL is shareware. If you like it and use it, please register your copy on the registration form enclosed at the end of this manual. You will be placed on a mailing list for future upgrades, and receive the most recent distribution disk. Online help is available through CompuServe, either by using EasyPlex or a message in IBMSW or IBMHW forums. Sorry, but online help is available ONLY to registered users. Help is also available by mail. I will try to answer all letters within 48 hours. Non-registered users must include a SASE for a reply. The degree of help available to non-registered users is purely discretionary. SERIAL and all related documentation may not be sold under any circumstances without prior approval of S.E. Margison. Public Domain/Shareware distributors and Users Groups may charge a nominal fee for copying and distributing this program and Bulletin Board Systems may likewise carry it. Please contact me for a complimentary copy to insure that you are offering the most recent and complete release. SERIAL and its documentation may not be transferred nor exchanged in any modified form. If you really want to "hack" the functions or the documentation, by all means do so; but don't give the hacked version to anyone else. I cannot be expected to help others use these functions if they are not the same as distributed. Under no circumstances may the copyright notices be altered or removed from the functions or documentation. SERIAL Manual Page 13 X. WARRANTY Oh, this shouldn't be necessary among friends and gentlemen, but it's really the lawyers who run the world and they say we gotta do this: ** SERIAL is hereby placed in the Public Domain, subject to the limitations specified in section IX of this manual. ** SERIAL and all documentation are copyright 1986 by Steven E. Margison. ** This program and documentation are provided "as is" without warranty of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. ** The user of this program and documentation agrees o hold the author and/or distributor(s) of this material harmless for any direct or consequential damages resulting from its use. In other words, "you're on your own!" ** If this material was received by the user on a diskette directly from the author (S.E. Margison) then the diskette will be warranted to be free from defects for a period of 30 days from date of purchase. Sole liability of the author shall be to replace such defective diskette with a like diskette upon return of the defective diskette. "Defective diskette" shall mean a diskette which is physically or magnetically damaged in such a way as to make the contained data inaccessible to a properly functioning computer of the type intended for the media. ** IBM is a registered trademark of International Business Machines Corporation. ** MS-DOS is a trademark of MicroSoft Corporation. If you are not already a registered user of one of my programs, a business-sized SASE will bring you a list of currently available programs from me. --- Steven E. Margison --- --- CompuServe 74435,1042 --- SERIAL Manual Page 14 ======================================================================= SOFTWARE REGISTRATION FORM AND ORDER ======================================================================= A separate form must be filled out for each product ordered or registered. This form may be photocopied, printed out, or edited to include all information and re-printed. PRODUCT: --------------- SERIAL --------------------------------------- Check all that apply: Amount: [ ] Standard registration $20.00 $______ TOTAL ENCLOSED: $______ If you already have these programs, where were they obtained? [ ]CompuServe [ ]Friend [ ]Employer [ ]BBS:__________________ Version_____ Serial No._________ Payment is by check[ ] or money order[ ] (Sorry - no COD or charges) NAME _______________________________________________________ COMPANY ____________________________________________________ ADDRESS ____________________________________________________ CITY _______________________________________________________ STATE___________________________ ZIP _______________________ ======================================================================= Send completed form and payment to: Steven E. Margison 124 Sixth Street Downers Grove, IL, 60515 ======================================================================= - do not write below this line - recd________ sent________ version_______ serial no.________ SERIAL Manual Page 15